package com.starhub.domain.knowledge.service;

import com.starhub.application.rag.vo.SegmentVo;
import com.starhub.domain.knowledge.dto.KnowledgeItemDto;
import com.starhub.domain.knowledge.result.KnowledgeItemsSearchResult;
import com.starhub.domain.knowledge.vo.KnowledgeBaseVo;
import com.starhub.domain.knowledge.vo.KnowledgeCollectionVo;
import com.starhub.domain.knowledge.vo.KnowledgeItemVo;

import java.util.List;

/**
 * 知识库Service接口
 * @version: V1.0
 * @author: liuhf
 * @time 2025-06-05
 */
public interface KnowledgeService {

    /**
     * 创建知识条目
     * @param knowledgeItem 知识条目信息
     * @return 是否创建成功
     */
    String createKnowledgeItem(KnowledgeItemDto knowledgeItem, boolean isFlush);

    /**
     * 更新知识条目
     * @param knowledgeItem 知识条目信息
     * @return 是否更新成功
     */
    boolean updateKnowledgeItem(KnowledgeItemDto knowledgeItem);

    /**
     * 删除知识条目（软删除）
     * @param id 知识条目ID
     * @return 是否删除成功
     */
    boolean deleteKnowledgeItem(Long id);

    /**
     * 根据ID获取知识库
     * @param id 知识库ID
     * @return 知识库信息
     */
    KnowledgeBaseVo getKnowledgeBaseById(Long id);

    
    /**
     * 根据ID获取知识库表
     * @param id 知识库表ID
     * @return 知识库表信息
     */
    KnowledgeCollectionVo getKnowledgeCollectionById(Long id);

    /**
     * 根据ID获取知识条目
     * @param id 知识条目ID
     * @return 知识条目信息
     */
    KnowledgeItemVo getKnowledgeItemById(Long id);

    /**
     * 根据内容获取知识条目
     * @param collectionId 知识库表ID
     * @param content 知识条目内容
     * @return 知识条目信息
     */
    KnowledgeItemVo getKnowledgeItemByContent(String collectionId, String content);


    /**
     * 分页查询知识条目
     * 
     * @param collectionId 知识库表ID
     * @param current 当前页码
     * @param size 每页大小
     * @param keyword 搜索关键词（可选）
     * @return 分页结果
     */
    KnowledgeItemsSearchResult pageKnowledgeItems(Long collectionId, Long current, Long size, String keyword);

    /**
     * 在指定知识库表中检索文本
     * @param collectionId 知识库表ID
     * @param queryText 检索文本
     * @param topK 返回最相似的前K条记录
     * @return 检索结果列表
     */
    List<SegmentVo> searchSegments(Long collectionId, String queryText, Integer topK, Double minScore);
} 